Amiga Format 16/af016.adf/Lib counter readme

Text File | 1978-01-04 | 13.3 KB | 302 lines

------------------------------------------------------------------------
Lib-Counter version 1.0
(c) Copyright Alan J. Edmonds  May, June 1990
------------------------------------------------------------------------
DISCLAIMER
Every effort has been made to produce a reliable, high quality program.
However I can neither guarantee nor be held legally responsible for any
errors in the program or for any loss or damage caused by the use of the
Program.

Alan J. Edmonds.
------------------------------------------------------------------------
1)   Introduction
------------------------------------------------------------------------
Lib-Counter will count and display (in real time!) the number of calls made
to any of the Amiga library routines which you care to select.  There are
basically two ways to look at Lib-Counter:-

1)  As a U.H.  (Useless Hack!)
2)  As a U.T.  (Useful Tool)

I'll let you make you're own mind up!

If you look at the right library routines,  Lib-Counter will give you an idea
of what the Amiga spends its time doing.  And if you're a programmer, you
might (that's a big MIGHT...) find Lib-Counter helpful with the testing of
your programs.  It can also tell you which library routines are used most
often by other programmers!

------------------------------------------------------------------------
2)   How to start the program
------------------------------------------------------------------------
Lib-Counter may be run directly from either CLI or Workbench.
From Workbench, just double click the Lib-Counter icon, and away you go!
From the CLI (with the program in your current directory) you can just enter:
Lib-Counter {RETURN}
Or to run it in the background and keep the CLI available for other uses:
RUN Lib-Counter {RETURN}

------------------------------------------------------------------------
3)   Using the program
------------------------------------------------------------------------

The entire program is controlled by selecting various gadgets with the
mouse (surely every Amiga user must know how to do that!)
When run, a copyright message is displayed - press either of the OK buttons
to continue.  The main window is then displayed with the following options:-

'Add A Counter...'
------------------
This gadget will bring up a display similar to a file requester, showing a
list of library names to select.  You can scroll through the list by
clicking the large up and down arrows.  To select a library, just point and
click on its name.  If you decide not to add a counter, click cancel.

Once a library has been selected, you will be presented with a list of
routine names for that particular library, which may be scrolled with the
arrows.
Choose the required routine by clicking on it.
If you want to select a different library instead, clicking LIBS will take
you back to the library name list.  Cancel takes you back to the main screen.

As soon as a routine is chosen, a counter will be initialised and displayed,
unless a problem occurrs - in which case an appropriate error message will
be displayed.

'Remove A Counter...'
---------------------

This option is identical to Add A Counter except that when you select a
routine, (you've guessed it!) the counter will be removed.  If the selected
routine didn't have a counter, an error message will appear.

'Remove All Counters'
---------------------

This will save you the trouble of doing many Remove A Counter operations, by
removing them all in one go.  If no counters are running, then nothing will
happen!

Note that there may be some disk access, because the program will open and
scan all the disk based libraries for counters, as well as the built in
ones.  So if you only have one disk drive,  a system requester may appear,
asking for you to insert the Workbench disk.

'Tidy Screens'
--------------

If you start up several counters, you'll find this option very useful.  It
will arrange all the counter screens in a neat stack at the bottom of the
display.
It will also bring any counter screens hidden behind the Workbench screen to
the front.
The Workbench screen is also moved to the top of the display (if it wasn't
there already)
If no counters are present then nothing will happen!

Note that only the first 10 counter screens that Tidy Screens finds are
moved.  If you want more than 10 at a time, then you'll have to position
them manually!

'About'
-------

Brings up a requester containing some details about the program!
Press one of the OK gadgets to continue.

'Quit'
------

Terminates the program.  Note that you may quit and leave counters running -
this will save about 35k of memory.  You may then re-run the program at any
time and (say) do a Remove All Counters or whatever.


Note about the requesters
-------------------------

If you select About or one of the errors listed below occurrs, then the
Workbench screen gets moved to the front of all the other screens -
including any counter screens you've got running.  Therefore, I have
provided two 'OK' gadgets in my 'Error', 'Copyright' and 'About' requesters
as follows:-
'OK' - this just removes the requester and leaves Workbench at the front.
'OK + Workbench to back' - pushes Workbench to the back of the display and
removes the requester.
This saves you from having to manipulate the screen to back / front gadgets.

------------------------------------------------------------------------
4)   Error messages
------------------------------------------------------------------------

Can't open that library
-----------------------
The selected library could not be found. You may have selected a library
which is disk based and not in your current LIBS: directory.
Some of the libraries in the list will not open.  I entered them as shown in
the 'Amiga ROM Kernel Reference Manual' and the 'Amiga System Programmers
Guide' - but they just won't open! (As far as I know these libraries were
used in earlier versions of the system and are now obsolete.)
The libraries in question are as follows:-

clist,  console,  potgo,  and timer.
(As I went to the trouble of entering all the data for these libraries, I
decided to leave them in.)

That routine already has a counter
----------------------------------
Only one counter per routine is allowed.  If you can't seem to find the
counter for that routine,  its screen may be behind the Workbench screen.
You might like to press 'Tidy Screens' to bring the counters to the front.

Couldn't find a counter there
-----------------------------
You asked for a counter to be removed where there isn't one.

Out of memory
-------------
You're really pushing things if you get this one!  Close some windows,  quit
one of the programs you're running or remove some counters, then try again.

(Another way around the 'Out Of Memory' error which I once read about was to
'Buy more memory'! - But I'm not going to put that one in.)

Unknown vector type
-------------------
Something is seriously wrong if you get this error.  Another program you are
using may have corrupted a library vector.  It may be the result of a virus.

----------------------------------------------------------------------
5)   Routines to try counters with
----------------------------------------------------------------------
Here is a list of some of the more interesting ones (Are there any ?):-

Graphics routines OwnBlitter and DisOwnBlitter - A surprisingly large number
of programs / tasks want to own the blitter!  Try moving a window or typing
& pressing return a few times in a CLI.
Graphics Draw (draws straight lines) - see how fast the counter goes as you
size or move windows!
Graphics Text - every character you type in a CLI calls Text.
Graphics MoveSprite - every time you move the mouse pointer, guess what will
happen to this counter...!
If FastFonts is switched on,  each time text is printed (say by typing in a
CLI),  the Graphics routines BltTemplate and BltPattern are called.
If FastFonts is off, BltClear is called in addition to these two.

Exec AllocMem and FreeMem - (allocate and free memory) get a lot of calling
- especially when you move a window in a crowded screen.

Exec Switch - This tends to give an indication of how busy the processor is,
by incrementing at a different rate for varying situations.
Exec OpenLibrary and Forbid - On my machine these two tick over at one count
per second!  (May be useful as a stopwatch ?!!!)
Exec FindTask - Every second, 3 tasks get 'looked for'!

Some libraries seem to get little or no use by the operating system via the
standard 'jump table' calling method.  For example, if you put a counter on
Intuition MoveWindow and try moving a window - nothing!  So, either
intuition does it internally, or perhaps the work gets done by other
Libraries - in this case the Layers library MoveLayer function.
The fact that counters added to Intuition (and Dos, to name another) are
relatively dead may be put to good use, because it means that any calls that
ARE made to their routines will probably be from an Applications program.
This makes it much easier to see what a program is doing, because any other
(systems) calls will not be shown on the counter.

----------------------------------------------------------------------
6)   'Technical notes'  (99% of people may want to skip this section)
----------------------------------------------------------------------
The program should run on any Amiga.  It was developed on a 1MB Amiga 500.
I also tested it with the RAM expansion switched off.  It will return all
memory and close all Libraries opened after all the counters are removed.

Lib-Counter ignores the current 60/80 character size value in preferences,
so that if you're set to 60, the text will not go off the end of the window.
 It's surprising how many other programs produce corrupted displays when the
60 column text size is in use!  (Sorry to TV only users)

Even though Lib-Counter is 100% Assembly Language,  the speed at which the
display updates in the library requesters may seem a little slow to some
people. The reason for this is that the intuition function RefreshGadgets is
SLOW (especially with > 10 gadgets to refresh) and I make 3 calls to it each
time an arrow is clicked.  I may change this in a future version.

A possible problem area is to use Lib-Counter with another program which
modifies the Library Vectors.  An example of such a program is FastFonts.
Not all will cause trouble; indeed FastFonts is good in this respect - if
you add a counter to Graphics/Text with FF off, and then run FF, it will
warn you about the modified vector and quit.  Other programs may not be so
carefull and this is something to bear in mind.  In other words, don't risk
using Lib-Counter just before you save something you've been working on for
4 hours!!!  Save your work, then play with it!
Having said that,  it hasn't crashed on me yet.

The program itself takes about 35k of system memory (some chip, some fast -
if available).  Each counter added consumes less than 3k - even though a new
screen is opened for each counter.  The reason for this is that the screen
height is set only a little taller than the title bar.
After much thought, I decided on using screens rather than (say) a large
window, in order to make each counter stand-alone.  With this method,  room
can usually be found for up to 5 counters at the bottom of the Workbench
screen without too much trouble - and this is where the 'Tidy Screens'
option places the screens.  I decided against making this option operate
automatically after each 'Add A Counter', so that the user may position the
screens differently and then add further counters without repeated
re-positioning.

When developing Lib-Counter I found the structure of the DOS library to be
different to the other libraries in the way that the jump table is composed.
(Perhaps everybody else knows this already - but I'll mention it anyway!)
The other libraries consist of the following type of jump table:-

JMP FCxxxx
JMP FCnnnn
etc

Whereas the DOS library goes:-
MOVEQ #0,D0
BRA xxxx
MOVEQ #0,D0
BRA nnnn

This caused a few headaches when it came to Adding a counter to a DOS
routine, because my program assumed that all the libraries contained JMP
instructions. It took what it thought to be the system routine address (to
go to after incrementing the counter) from the last 4 bytes of the library
vector - but in the case of DOS this was a BRA instruction!  Therefore, any
call to the selected DOS routine caused a spectacular crash!  After I
discovered this,  I changed the program to test the vector type before
deciding what to do - and it now works with all the current (and hopefully
future) Library Vector types.

I would also like to mention another small problem I had in the development
stages.  At first, I used the Graphics routines Move and Text to print the
counter value every time it changed.  However, if a counter was added to
Text, Move or any routine called by Text or Move (e.g. OwnBlitter) then a
continuous loop was formed.  To solve this problem, the program writes its
own font data directly to the screen bitmap.

----------------------------------------------------------------------
My address:-
----------------------------------------------------------------------
If anybody wants to contact me (for example to send me their unwanted gifts
such as an A3000, Hard Disk Drive, Laser Printer ... should I go on ?) then
please write to :-

Alan J. Edmonds
5 Beatrice Street
Latchford
Warrington
Cheshire
WA4 1DR

{England}

I would also be interested in bug reports, comments (reasonably friendly
ones, please) etc.

END OF FILE